| Copyright | (c) 2019 Oleg Grenrus |
|---|---|
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Distribution.Utils.Structured
Description
Structurally tag binary serialisation stream.
Useful when most Binary instances are Generic derived.
Say you have a data type
data Record = Record
{ _recordFields :: HM.HashMap Text (Integer, ByteString)
, _recordEnabled :: Bool
}
deriving (Eq, Show, Generic)
instance Binary Record
instance Structured Record
then you can serialise and deserialise Record values with a structure tag by simply
structuredEncoderecord ::ByteStringstructuredDecodelbs :: IO Record
If structure of Record changes in between, deserialisation will fail early.
Technically, Structured is not related to Binary, and may
be useful in other uses.
Synopsis
- structuredEncode :: forall a. (Binary a, Structured a) => a -> ByteString
- structuredEncodeFile :: (Binary a, Structured a) => FilePath -> a -> IO ()
- structuredDecode :: forall a. (Binary a, Structured a) => ByteString -> a
- structuredDecodeOrFailIO :: (Binary a, Structured a) => ByteString -> IO (Either String a)
- structuredDecodeFileOrFail :: (Binary a, Structured a) => FilePath -> IO (Either String a)
- class Typeable a => Structured a where
- type MD5 = Fingerprint
- structureHash :: forall a. Structured a => Proxy a -> MD5
- structureBuilder :: Structure -> Builder
- genericStructure :: forall a. (Typeable a, Generic a, GStructured (Rep a)) => Proxy a -> Structure
- class GStructured (f :: Type -> Type)
- nominalStructure :: Typeable a => Proxy a -> Structure
- containerStructure :: forall f a. (Typeable f, Structured a) => Proxy (f a) -> Structure
- data Structure
- data Tag a = Tag
- type TypeName = String
- type ConstructorName = String
- type TypeVersion = Word32
- type SopStructure = [(ConstructorName, [Structure])]
- hashStructure :: Structure -> MD5
- typeVersion :: Functor f => (TypeVersion -> f TypeVersion) -> Structure -> f Structure
- typeName :: Functor f => (TypeName -> f TypeName) -> Structure -> f Structure
Encoding and decoding
These functions operate like binary's counterparts,
but the serialised version has a structure hash in front.
structuredEncode :: forall a. (Binary a, Structured a) => a -> ByteString Source #
Structured encode.
Encode a value to using binary serialisation to a lazy ByteString.
Encoding starts with 16 byte large structure hash.
structuredEncodeFile :: (Binary a, Structured a) => FilePath -> a -> IO () Source #
Lazily serialise a value to a file
structuredDecode :: forall a. (Binary a, Structured a) => ByteString -> a Source #
Structured decode.
Decode a value from a lazy ByteString, reconstructing the original structure.
Throws pure exception on invalid inputs.
structuredDecodeOrFailIO :: (Binary a, Structured a) => ByteString -> IO (Either String a) Source #
structuredDecodeFileOrFail :: (Binary a, Structured a) => FilePath -> IO (Either String a) Source #
Lazily reconstruct a value previously written to a file.
Structured class
class Typeable a => Structured a where Source #
Class of types with a known Structure.
For regular data types Structured can be derived generically.
data Record = Record { a :: Int, b :: Bool, c :: [Char] } deriving (Generic)
instance Structured Record
Since: 3.2.0.0
Minimal complete definition
Nothing
Methods
Instances
structureHash :: forall a. Structured a => Proxy a -> MD5 Source #
Semantically hashStructure . structure
structureBuilder :: Structure -> Builder Source #
genericStructure :: forall a. (Typeable a, Generic a, GStructured (Rep a)) => Proxy a -> Structure Source #
Derive structure generically.
class GStructured (f :: Type -> Type) Source #
Used to implement genericStructure.
Minimal complete definition
gstructured
Instances
| (i ~ D, Datatype c, GStructuredSum f) => GStructured (M1 i c f) Source # | |
Defined in Distribution.Utils.Structured Methods gstructured :: TypeRep -> Proxy (M1 i c f) -> TypeVersion -> Structure | |
containerStructure :: forall f a. (Typeable f, Structured a) => Proxy (f a) -> Structure Source #
Structure type
Structure of a datatype.
It can be infinite, as far as TypeReps involved are finite.
(e.g. polymorphic recursion might cause troubles).
Constructors
| Nominal !TypeRep !TypeVersion TypeName [Structure] | nominal, yet can be parametrised by other structures. |
| Newtype !TypeRep !TypeVersion TypeName Structure | a newtype wrapper |
| Structure !TypeRep !TypeVersion TypeName SopStructure | sum-of-products structure |
Instances
| Generic Structure Source # | |
| Show Structure Source # | |
| Eq Structure Source # | |
| Ord Structure Source # | |
| type Rep Structure Source # | |
Defined in Distribution.Utils.Structured type Rep Structure = D1 ('MetaData "Structure" "Distribution.Utils.Structured" "Cabal-syntax-3.13.0.0-inplace" 'False) (C1 ('MetaCons "Nominal" 'PrefixI 'False) ((S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeRep) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeVersion)) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 TypeName) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Structure]))) :+: (C1 ('MetaCons "Newtype" 'PrefixI 'False) ((S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeRep) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeVersion)) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 TypeName) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Structure))) :+: C1 ('MetaCons "Structure" 'PrefixI 'False) ((S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeRep) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeVersion)) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 TypeName) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 SopStructure))))) | |
Constructors
| Tag |
type ConstructorName = String Source #
type TypeVersion = Word32 Source #
A semantic version of a data type. Usually 0.
type SopStructure = [(ConstructorName, [Structure])] Source #
typeVersion :: Functor f => (TypeVersion -> f TypeVersion) -> Structure -> f Structure Source #
A van-Laarhoven lens into TypeVersion of Structure
typeVersion:: Lens'StructureTypeVersion